!HID User Manual - Joysticks

Joysticks - Technical backgrounds |

From version 0.22 onwards, !HID is supplied with a Joystick module that allows the state of any of the USB joysticks to be read and used by your software. The entire functionality of the Joystick module is implemented so any existing software that uses the Joystick interface, should theoretically work straight away. There are three ways for your software to read the state of the joysticks:

Using the Joystick SWIs Using a set of OS_Byte calls Using the BASIC function ADVAL

In addition to this, the range of SWI calls has been extended and new reason codes have been added to the existing SWI Joystick_Read. Furthermore, some useful *-commands have been added to allow flexible configuration of the software.

Joystick module version number |

The Joystick module is numbered from 3.00 upwards as to avoid confusion with existing modules and software. The initial Joystick module supplied by Acorn on some RISC OS 3 computers, always has a version number of 1.xx. Third party Joystick modules should have a version of 2.xx so that the Acorn module can be replaced automatically. As we've extended the API (Application Programmers Interface), we will use version numbers 3.xx from now on. If your software want's to access any of the new features, please check the module's version number prior to calling them.

Standard Joystick SWI calls |

The Joystick module supports the standard SWI calls as specified by Acorn in PRM-5a on page 629. Please refer to the PRM for further information. As the documentation contains quite a number of typos, the SWIs are listed again here.

Joystick_Read 0 (SWI &43F40) This is the principle method to read the joystick X and Y position in 8-bit format. The call is present from RISC OS 3.00 onwards. The joysticks are numbered from 0 onwards. Entry: r0 : Joystick number (bits 0-7) and reason code (bits 8-15). Exit: r0 : 8-bit joystick state (see below}. Joystick state: (returned in r0 on exit) bits 0-7: signed Y value in the range -127 (down) to 127 (up). bits 8-15: signed X value in the range -127 (left) to 127 (right). bits 16-23: switches (e.g. fire buttons) starting in bit 16. bits 24-31: reserved. (Extended: now contains 8 extra buttons) Joystick_Read 1 (SWI &43F40) This call is available from RISC OS 3.60 onwards and allows the joystick X and Y position to be read in 16-bit format. The values for X and Y are in the range 0-65535 (i.e. 16 bits) and are combined into a single 32-bit word which is returned in r0 on exit. The state of the switches is returned in r1 and any unimplemented switch is returned as 0. Entry: r0 : Joystick number (bits 0-7) and reason code 1 (bits 8-15). Exit: r0 : Joystick Y positon (bits 0-15) and X position (bits 16-31). r1 : Switches (bits 0-7) starting in bit 0 (e.g. fire button). )Extended: now contains all buttons) Joystick_CalibrateTopRight (SWI &43F41) As analogue joysticks might be inacurate, it is necessary to calibrate them in order to make them return the full range of values. This SWI should be called with all joysticks (and additional controls) held in the top right position. This SWI call is one of a pair of SWIs (see below) that need to be called both before the joystick interface can be used properly. Once you have called only one of this pair of SWIs, Joystick_Read and the BASIC ADVAL command will return an error, until the process of calibration has been completed by calling the other one of the pair. Joystick_CalibrateBottomLeft (SWI &43F42) As analogue joysticks might be inacurate, it is necessary to calibrate them in order to make them return the full range of values. This SWI should be called with all joysticks (and additional controls) held in the bottom left position. This SWI call is one of a pair of SWIs (see below) that need to be called both before the joystick interface can be used properly. Once you have called only one of this pair of SWIs, Joystick_Read and the BASIC ADVAL command will return an error, until the process of calibration has been completed by calling the other one of the pair.

Standard OS_Byte calls |

The Joystick module adds some new OS_Byte calls and extends the range of reason codes of some others. This is done to ensure that the module is backwards compatible with existing software. The same OS_Byte calls are used by the Acorn Joystick module in RISC OS 3.6 and the BBC I/O Podule. The OS_Byte calls are detailed below, but you are advised to use the SWI calls when writing new software.

OS_Byte 16 (SWI &06) Stores the number of channels to be sampled. Entry: r0 : 16 (reason code) r1 : number of channels to be sampled (0-4) Exit: r0 : preserved OS_Byte 17 (SWI &06) Returns to the caller, doing nothing. Entry: r0 : 17 (reason code) r1 : channel number on which to force ADC conversion (0-4) Exit: r0 : preserved OS_Byte 128, 0-4 (SWI &06) Returns the switch state and last channel converted or a channel's uncalibrated position. This is an extension to the existing OS_Byte 128 call. Entry: r0 : 128 (reason code) r1 : sub-reason code 0 : return the switch state and number of last channel converted. 1-4 : channel number for which to return position. Exit: r0 : preserved r1 : state of switch 0 on joysticks 0 (bit 0) and 1 (bit 1), if r0 was 0 on entry. Low byte of 16 bit joystick position, if r0 was 0-4 on entry. r2 : Number of last channel converted, if r0 was 0 on entry. High of 16 bit joystick position, if r0 was 0-4 on entry. OS_Byte 188 (SWI &06) Reads the current channel. Entry: r0 : 188 (reason code) Exit: r0 : preserved r1 : current channel (1-4) OS_Byte 189 (SWI &06) Reads the current channel. Entry: r0 : 189 (reason code) Exit: r0 : preserved r1 : number of channels to be sampled (1-4) OS_Byte 190 (SWI &06) Reads the resolution of conversion. Entry: r0 : 190 (reason code) Exit: r0 : preserved r1 : 0 (i.e. the default conversion, which is 16-bit)

BASIC ADVAL function |

Whenever the joystick module is present, the ADVAL function in BASIC is extended automatically. The syntax is ADVAL(argument) and the argument is in the range 0-5. THe functionality is identical to OS_Byte 128, 0-4 (see above). Argument: 0 : Read the state of the switch (fire button) on both joysticks (bits 0 and 1). 1-4 : Channel number for which to return position. Position: The returned position is a 16 bit value (0-65635) with 32768 being the centre position. Reading the ADVAL function with no joystick(s) connected, always return the centre position to avoid joystick simulation software being confused.

Limitations of the current calls |

The above calls were implemented at a time when analogue joysticks were just becoming available. As a result most calls can only cope with up to two joysticks and the values are limited to X and Y movement only. As most modern joysticks have a variety of controls, including sliders, Z-axis movement, rotation, multiple buttons, etc., it was neccesary to add some new SWI calls. When writing new software, you should use the new calls whenever posssible, unless your software needs to be backward compatible with older versions of the OS. The new calls provide higher accuracy and more detailed information than the existing calls.

New SWI calls |

The new SWI calls are in the same range as the existing ones and they are available from version 3.00 of the module onwards.

Joystick_Read 2 (SWI &43F40) This is an extension to the existing SWI Joystick_Read. The call returns a pointer to a structure containing all data of the joystick. Entry: r0 : Joystick number (bits 0-7) and reason code 2 (bits 8-15). Exit: r0 -> Structure containing a number of 32-bit results. +0 : Number of parameters following +4 : Buttons (up to 32 buttons starting in bit 0) +8 : X position (0-65535) +12 : Y position (0-65535) +16 : Z position (0-65535) +20 : X rotation (0-65535) +24 : Y rotation (0-65535) +28 : Z rotation (0-65535) +32 : Slider (0-65535) +36 : HatSwitch (-1 if off, otherwise angle in degrees (0-315) Use: The first word of the structure gives the number of parameters following, so that it can be extended in the future. Your code should check the first word before trying to read past the end of the list. The Joystick module maintains this structure for each channel, so there is no need to make your own local copy of it. Joystick_Info 0 (SWI &43F43) Read global information from the Joystick module. Entry: r0 : 0 (reason code) Exit: r0 : Number of active joysticks (bits 0-7) and flags (bits 8-31). r1-r4: May be corrupted (may contain information in future versions of the call). Flags: bit 8 : Calibrated (both SWIs have been called). bit 9 : Fake calibration. Joystick_Info 1 (SWI &43F43) Read global information about a joystick port. Entry: r0 : 1 (reason code) r1 : Joystick port number Exit: r0 : Channel number (bits 0-7) and flags (bits 8-31). r1 : DeviceID (USB Vendor and Product code). Flags: bit 8 : Calibrated (both SWIs have been called). bit 9 : Fake calibration. Joystick_Info 2 (SWI &43F43) Read controls calibration. THIS CALL IS FOR INTERNAL USE ONLY. Joystick_Calibrate (SWI &43F44) Provides flexible calibration for each joystick individually. Entry: r0 : Joystick port number r1 : Calibration type 0 : Reset calibration 1 : Calibrate Bottom Left 2 : Calibrate Top Right 3 : Set fake calibration flag 4 : Reset calibrated flag r2 : Parameter to calibrate 0 : All parameters (should be 0 for now). Exit: All registers preserved.

Related subjects |

Using joysticks with !HID Main index

| © Copyright Paul Reuvers X-Ample Technology bv usb@xat.nl Last changed: Last changed: Saturday, 22 April 2006 - 15:20 CET.